Skip to content

Add Steps concept and durable execution docs for AI Transport#3459

Merged
zknill merged 10 commits into
mainfrom
durable-execution
Jul 10, 2026
Merged

Add Steps concept and durable execution docs for AI Transport#3459
zknill merged 10 commits into
mainfrom
durable-execution

Conversation

@zknill

@zknill zknill commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

Document the Step primitive and the durable-execution pattern that runs AI Transport agents inside a workflow engine. A Step is the re-attemptable unit of output within a Run; a retry under the same stepId supersedes the failed attempt on the channel rather than appending beside it, which is what makes a Run safe to execute across process boundaries and workflow retries.

New pages:

  • concepts/steps: the Step model, lifecycle, and supersede-on-retry semantics, with a diagram.

  • features/durable-execution: adopt an in-flight Run from a fresh process, retry a failed Step under a stable stepId, close the Run on exhausted retries.

  • frameworks/temporal, getting-started/temporal: the reference workflow-engine integration, with the openRun / first-inference activity split and channel-routed cancels.

  • api/javascript/temporal: the stepIdFor helper.

Extend agent-session API reference with adoptRun, createStep, detach, and RunStep. Add the ai-step-start / ai-step-end events and step headers to the wire protocol. Cross-link Steps and durable execution from the Runs, Sessions, tool-calling, reconnection, and going-to-production pages, and add nav entries. Promote durable execution to "Available today" on the roadmap.

@coderabbitai

coderabbitai Bot commented Jul 7, 2026

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 48684d43-9faa-46fd-94a8-f4047bd2f14e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch durable-execution

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@zknill zknill added the review-app Create a Heroku review app label Jul 7, 2026
@ably-ci ably-ci temporarily deployed to ably-docs-durable-execu-qgvjt6 July 7, 2026 15:36 Inactive
@ably-ci ably-ci temporarily deployed to ably-docs-durable-execu-qgvjt6 July 9, 2026 08:48 Inactive
@zknill zknill force-pushed the durable-execution branch from 347049f to 53710fb Compare July 9, 2026 08:49
@ably-ci ably-ci temporarily deployed to ably-docs-durable-execu-qgvjt6 July 9, 2026 08:49 Inactive
@zknill zknill force-pushed the durable-execution branch from 53710fb to c348d31 Compare July 9, 2026 09:19
@ably-ci ably-ci temporarily deployed to ably-docs-durable-execu-qgvjt6 July 9, 2026 09:19 Inactive
@zknill zknill force-pushed the durable-execution branch from c348d31 to 10f64b7 Compare July 9, 2026 09:52
@ably-ci ably-ci temporarily deployed to ably-docs-durable-execu-qgvjt6 July 9, 2026 09:52 Inactive
@ably-ci ably-ci temporarily deployed to ably-docs-durable-execu-qgvjt6 July 9, 2026 09:56 Inactive
@ably-ci ably-ci temporarily deployed to ably-docs-durable-execu-qgvjt6 July 9, 2026 09:59 Inactive
@zknill zknill force-pushed the durable-execution branch from b84eb55 to 7e2d018 Compare July 9, 2026 10:05
@ably-ci ably-ci temporarily deployed to ably-docs-durable-execu-qgvjt6 July 9, 2026 10:05 Inactive
Comment thread src/data/languages/languageData.ts Outdated
Comment thread src/pages/docs/ai-transport/api/javascript/core/agent-session.mdx Outdated
Comment thread src/pages/docs/ai-transport/features/durable-execution.mdx Outdated
Comment thread src/pages/docs/ai-transport/features/durable-execution.mdx Outdated
Comment thread src/pages/docs/ai-transport/concepts/steps.mdx Outdated
Comment thread src/pages/docs/ai-transport/api/javascript/temporal/index.mdx Outdated
Comment thread src/pages/docs/ai-transport/features/durable-execution.mdx Outdated
Comment thread src/pages/docs/ai-transport/frameworks/temporal.mdx Outdated
Comment thread src/pages/docs/ai-transport/frameworks/temporal.mdx Outdated
zknill added a commit that referenced this pull request Jul 9, 2026
Apply review feedback from PR #3459, correcting statements that
diverged from actual SDK behaviour and house conventions.

- Correct the retry-supersede edge case: a retry supersedes the prior
  attempt the moment it calls step.start(), because supersede keys on
  the fresh higher-serial ai-step-start under the same stepId, not on
  any output the retry produces.

- Qualify Realtime-client sharing as same-process only; Temporal and
  Vercel Workflow DevKit isolate each activity in its own process, and
  clarify that session objects must not be shared across activities.

- Use key: process.env.ABLY_API_KEY instead of authUrl in server-side
  and agent code samples, where an API key is the correct credential.

- Reference session.end()/session.detach() rather than the
  non-existent session.close() on AgentSession.

- Add 'cancelled' to the terminal StepEndReason list.

- Use "realtime" (one word) per house style.

- Align the AI Transport SDK version to the two-part '0.5' format used
  by sibling entries in languageData.ts.
@zknill zknill force-pushed the durable-execution branch from 7e2d018 to f3bc49c Compare July 9, 2026 13:31
@ably-ci ably-ci temporarily deployed to ably-docs-durable-execu-qgvjt6 July 9, 2026 13:32 Inactive
@zknill zknill requested a review from VeskeR July 9, 2026 13:34

@VeskeR VeskeR left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, there are still a couple of outdated AgentSession.close() references and StepEndReason not mentioning cancelled - I'm going to address it in my #3463 (see AI Transport docs: align session teardown and step end reasons with SDK commit)

Document the Step primitive and the durable-execution pattern that runs
AI Transport agents inside a workflow engine. A Step is the re-attemptable
unit of output within a Run; a retry under the same stepId supersedes the
failed attempt on the channel rather than appending beside it, which is
what makes a Run safe to execute across process boundaries and workflow
retries.

New pages:

- concepts/steps: the Step model, lifecycle, and supersede-on-retry
  semantics, with a diagram.

- features/durable-execution: adopt an in-flight Run from a fresh
  process, retry a failed Step under a stable stepId, close the Run on
  exhausted retries.

- frameworks/temporal, getting-started/temporal: the reference
  workflow-engine integration, with the openRun / first-inference
  activity split and channel-routed cancels.

- api/javascript/temporal: the stepIdFor helper.

Extend agent-session API reference with adoptRun, createStep, detach,
and RunStep. Add the ai-step-start / ai-step-end events and step headers
to the wire protocol. Cross-link Steps and durable execution from the
Runs, Sessions, tool-calling, reconnection, and going-to-production
pages, and add nav entries. Promote durable execution to "Available
today" on the roadmap.
zknill added 5 commits July 10, 2026 09:29
A verbatim run-through of the Temporal getting-started guide in a fresh
Next.js project surfaced compile and setup failures. Correct the guide
and the pages it links to so a reader who follows it can build and run.

- Pin the install command to the API's target release
  (@ably/ai-transport@^0.5.0) and the compatible AI SDK line
  (ai@^6, @ai-sdk/*@^3), and add deps the guide's own code uses but the
  command omitted: zod, tsx, jsonwebtoken, and the dev typings.

- Add a "Set up the project" section: ESM package.json with the worker
  script, next.config serverExternalPackages for the Temporal client,
  and the required .env keys.

- Type the guide's runInference activity (VercelAgentRun alias) so it
  compiles under strict TypeScript.

- authentication: grant the conversations:* namespace so the token
  authorizes the channel clients actually open, define the referenced
  authenticateUser, type the handler, and guard ABLY_API_KEY.

- vercel-ai-sdk: type the Providers component and Ably client state.

- temporal API reference: drop the incidental "first activity is 1"
  sentence.
Apply review feedback from PR #3459, correcting statements that
diverged from actual SDK behaviour and house conventions.

- Correct the retry-supersede edge case: a retry supersedes the prior
  attempt the moment it calls step.start(), because supersede keys on
  the fresh higher-serial ai-step-start under the same stepId, not on
  any output the retry produces.

- Qualify Realtime-client sharing as same-process only; Temporal and
  Vercel Workflow DevKit isolate each activity in its own process, and
  clarify that session objects must not be shared across activities.

- Use key: process.env.ABLY_API_KEY instead of authUrl in server-side
  and agent code samples, where an API key is the correct credential.

- Reference session.end()/session.detach() rather than the
  non-existent session.close() on AgentSession.

- Add 'cancelled' to the terminal StepEndReason list.

- Use "realtime" (one word) per house style.

- Align the AI Transport SDK version to the two-part '0.5' format used
  by sibling entries in languageData.ts.
Clarify the auth guidance so agents stop rewriting valid server-side
code, and add the "realtime" spelling rule that was previously only
enforced by hand.

- Principle 17 now states the client/server split explicitly: browser
  code uses authUrl, but server-side and agent code (activities, agent
  routes, workers) must use key: process.env.ABLY_API_KEY. An authUrl
  in a server snippet is a bug, not a pattern to preserve.

- Note why the client-key verification grep passes process.env-sourced
  keys, so the exception is visible at the check itself.

- Add "realtime" (one word) as an enforced spelling, with a sweep grep
  in the verification block.
@zknill zknill force-pushed the durable-execution branch from f3bc49c to da6473c Compare July 10, 2026 08:29
@ably-ci ably-ci temporarily deployed to ably-docs-durable-execu-qgvjt6 July 10, 2026 08:30 Inactive
VeskeR and others added 3 commits July 10, 2026 09:48
Document running the AI Transport SDK on Vercel Workflow Development Kit
(Vercel WDK), the in-app durable-execution integration, alongside the existing
Temporal one.

- frameworks/workflow-devkit: how AI Transport composes with Vercel WDK. The
  workflow opens the Run and runs each model call and tool as its own WDK step,
  using the WDK step id as the AI Transport Step id so a retry supersedes the
  failed attempt on the channel rather than appending beside it. Covers the
  driver-owned tool loop for server, client-executed, and approval-gated tools,
  channel-routed cancels, and suspend and resume across workflows.
- getting-started/workflow-devkit: a Next.js walkthrough that opens the Run and
  runs each inference as its own retryable step, with a flaky tool that shows a
  retry superseding the failed attempt on the channel.

Add the two framework diagrams, nav entries under By SDK and Frameworks, and
cross-links from the Steps, durable-execution, tool-calling, concepts, roadmap,
going-to-production, and Temporal pages.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two documentation-wide accuracy fixes against @ably/ai-transport v0.5.0.

AgentSession no longer has close(): teardown is end(), which closes any
still-open Run as `cancelled` then detaches. detach() alone is reserved for
durable cross-process handoff. Every agent-side example that tore down with
session.close() now uses session.end(), and the connections concept describes
the ClientSession/AgentSession teardown split correctly. Client-side
ClientSession.close() is unchanged.

StepEndReason is `complete` | `failed` | `cancelled`: a cancel arriving while a
Step is open closes ai-step-end{cancelled} before the Run ends. The Steps
concept, the AgentSession step-end reference (including the end() default
derivation), and the wire-protocol step-reason header and ai-step-end rows now
list all three. The Run-level run-reason (RunEndReason) is left as
complete/cancelled/error.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A write-docs review pass over the Vercel WDK pages tightened wording and
corrected two mechanism descriptions that misstated how the SDK behaves.

On the framework page, the supersede explanation attributed the prompt-ordering
guarantee to a "short wait" and said the publish ack does not guarantee it. The
guarantee is awaiting step.start(): it folds the superseding, higher-serial
ai-step-start into the read model behind run.view before it resolves, so reading
the view straight after is already clean. The cancel edge case claimed a later
cancel is replayed from channel history when load() resolves; cancels route only
through the live channel subscription, so the text now matches the SDK and demo.

The rest is phrasing: "realtime" spelling, a de-duplicated "owns its half of the
job" metaphor, an active-voice bullet, and a fifth Explore-next link.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@ably-ci ably-ci temporarily deployed to ably-docs-durable-execu-qgvjt6 July 10, 2026 08:48 Inactive
@ably-ci ably-ci temporarily deployed to ably-docs-durable-execu-qgvjt6 July 10, 2026 09:16 Inactive
@zknill zknill merged commit d6a9dc3 into main Jul 10, 2026
6 checks passed
zknill added a commit that referenced this pull request Jul 10, 2026
Apply review feedback from PR #3459, correcting statements that
diverged from actual SDK behaviour and house conventions.

- Correct the retry-supersede edge case: a retry supersedes the prior
  attempt the moment it calls step.start(), because supersede keys on
  the fresh higher-serial ai-step-start under the same stepId, not on
  any output the retry produces.

- Qualify Realtime-client sharing as same-process only; Temporal and
  Vercel Workflow DevKit isolate each activity in its own process, and
  clarify that session objects must not be shared across activities.

- Use key: process.env.ABLY_API_KEY instead of authUrl in server-side
  and agent code samples, where an API key is the correct credential.

- Reference session.end()/session.detach() rather than the
  non-existent session.close() on AgentSession.

- Add 'cancelled' to the terminal StepEndReason list.

- Use "realtime" (one word) per house style.

- Align the AI Transport SDK version to the two-part '0.5' format used
  by sibling entries in languageData.ts.
@zknill zknill deleted the durable-execution branch July 10, 2026 09:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review-app Create a Heroku review app

Development

Successfully merging this pull request may close these issues.

3 participants